<h2>DESCRIPTION</h2>

<em>i.maxlik</em> is a maximum-likelihood discriminant
analysis classifier.  It can be used to perform the second
step in either an unsupervised or a supervised image
classification.

<p>
Either image classification methods are performed in two
steps.  The first step in an unsupervised image
classification is performed by
<em><a href="i.cluster.html">i.cluster</a></em>; the first step in a
supervised classification is executed by the GRASS
program <em><a href="g.gui.iclass.html">g.gui.iclass</a></em>
(or by providing any other raster map with already existing
training areas). In both cases, the second step in
the image classification procedure is
performed by <em>i.maxlik</em>.

<p>
In an unsupervised classification, the maximum-likelihood
classifier uses the cluster means and covariance matrices
from the <em><a href="i.cluster.html">i.cluster</a></em>
signature file to determine to which category (spectral
class) each cell in the image has the highest probability
of belonging. In a supervised image classification, the
maximum-likelihood classifier uses the region means and
covariance matrices from the spectral signature file
generated by <em>
<a href="g.gui.iclass.html">g.gui.iclass</a></em>, based on regions
(groups of image pixels) chosen by the user, to determine
to which category each cell in the image has the highest
probability of belonging.

<p>
In either case, the raster map output by
<em>i.maxlik</em> is a classified image in which each cell
has been assigned to a spectral class (i.e., a category).
The spectral classes (categories) can be related to
specific land cover types on the ground.

<h2>NOTES</h2>

The maximum-likelihood classifier assumes that the spectral 
signatures for each class (category) in each band file
are normally distributed (i.e., Gaussian in nature).
Algorithms, such as
<em><a href="i.cluster.html">i.cluster</a></em>,
<em><a href="g.gui.iclass.html">g.gui.iclass</a></em>,
or <em><a href="i.gensig.html">i.gensig</a></em>,
however, can create signatures that are not valid 
distributed (more likely with 
<em><a href="g.gui.iclass.html">g.gui.iclass</a>).</em>
If this occurs, 
<em>i.maxlik</em>
will reject them and display a warning message.

<p>
The signature file (<b>signaturefile</b>) contains the cluster and
covariance matrices that were calculated by the GRASS
program <em><a href="i.cluster.html">i.cluster</a></em> (or the region
means and covariance matrices generated by
<em><a href="g.gui.iclass.html">g.gui.iclass</a></em>, if the user
runs a supervised classification). These spectral signatures are what
determine the categories (classes) to which image pixels will be
assigned during the classification process.

<p>
The optional name of a <b>reject</b> raster map holds the reject
threshold results. This is the result of a chi square test on each
discriminant result at various threshold levels of confidence to
determine at what confidence level each cell classified
(categorized). It is the reject threshold map layer, and contains the
index to one calculated confidence level for each classified cell in
the classified image. 16 confidence intervals are predefined, and the
reject map is to be interpreted as 1 = keep and 16 = reject. One of
the possible uses for this map layer is as a mask, to identify cells
in the classified image that have a low probability (high reject
index) of being assigned to the correct class.

<h2>EXAMPLE</h2>

Second part of the unsupervised classification of a LANDSAT subscene
(VIZ, NIR, MIR channels) in North Carolina (see
<em><a href="i.cluster.html">i.cluster</a></em> manual page for the first
part of the example):

<div class="code"><pre>
# using here the signaturefile created by i.cluster
i.maxlik group=lsat7_2002 subgroup=res_30m \
  signaturefile=cluster_lsat2002 \
  output=lsat7_2002_cluster_classes reject=lsat7_2002_cluster_reject

# visually check result
d.mon wx0
d.rast.leg lsat7_2002_cluster_classes
d.rast.leg lsat7_2002_cluster_reject

# see how many pixels were rejected at given levels
r.report lsat7_2002_cluster_reject units=k,p

# optionally, filter out pixels with high level of rejection
# here we remove pixels of at least 90% of rejection probability, i.e. categories 12-16
r.mapcalc "lsat7_2002_cluster_classes_filtered = \
           if(lsat7_2002_cluster_reject &lt;= 12, lsat7_2002_cluster_classes, null())"
</pre></div>

<!--
saved using d.mon wx0; d.rast lsat7_2002_cluster_classes; and save
then trimmed using mogrify -trim *.png
-->
<p>
<center>
<img src="i_maxlik_rgb.png"><br>
RGB composite of input data
<p>
<img src="i_maxlik_classes.png"><br>
Output raster map with pixels classified (10 classes)
<p>
<img src="i_maxlik_rejection.png"><br>
Output raster map with rejection probability values (pixel classification confidence levels)
</center>


<h2>SEE ALSO</h2>

<a href="https://grasswiki.osgeo.org/wiki/Image_processing">Image processing</a>
and
<a href="https://grasswiki.osgeo.org/wiki/Image_classification">Image classification</a>
wiki pages and for historical reference also
the GRASS GIS 4<em>
<a href="https://grass.osgeo.org/gdp/imagery/grass4_image_processing.pdf">Image
Processing manual</a></em>

<p>
<em>
<a href="g.gui.iclass.html">g.gui.iclass</a>,
<a href="i.cluster.html">i.cluster</a>,
<a href="i.gensig.html">i.gensig</a>,
<a href="i.group.html">i.group</a>,
<a href="i.segment.html">i.segment</a>,
<a href="i.smap.html">i.smap</a>,
<a href="r.kappa.html">r.kappa</a>
</em>

<h2>AUTHORS</h2>

Michael Shapiro,
U.S.Army Construction Engineering 
Research Laboratory
<br>
Tao Wen, 
University of Illinois at Urbana-Champaign,
Illinois
<br>
Band reference support: Maris Nartiss,
University of Latvia

<!--
<p>
<i>Last changed: $Date$</i>
-->
